Alteryx SDKのHTML GUI設定

「カスタマーストーリー」を支えるツール特集

#HTML

#Alteryx SDK

#ビッグデータ

#Alteryx

じょんすみす

2018.02.14

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、小澤です。

今回はAlteryx SDKのうち、インターフェース部分の設定をする機能について解説させていただきます。なお、Alteryxの公式ドキュメントなどではHTML GUIと表記されていますので、ここではGUIと表記します。

マクロにおけるインターフェース

さて、まずはマクロ(Analytic App)でのインターフェースの設定方法についておさらいしておきましょう。

マクロの作成時にはインターフェースツールを利用していました。インターフェースツールをワークフロー上に設置すると、その項目がマクロを利用した際の設定画面に表示されます。

SDKを使ってツールを作る際にも、同様に設定項目を入れるためのGUIを作成する必要があります。

しかし、SDKの場合、マクロでのワークフローに相当する部分がプログラムになるため、インターフェースツールを配置することができません。これを実現するために、HTML5を使ってGUIを設計するのが今回紹介する設定になります。

実はマクロでも使えるHTML GUI

さて、実はこのHTMLを使ったインターフェースですが、実はマクロ作成時にも利用できます。一部のツールでは、以下のようにインターフェースツールとは異なるUIのデザインになっているのが確認できます。

このようなことが実現できるため、今回紹介するインターフェースはSDKからの利用のみではなく、yxi形式で配布するマクロでも利用できます。

HTML GUIの設定

Alteryxのライブラリを読み込む

AlteryxのGUIの設定では、独自のタグやJavaScriptライブラリを利用します。そのため、ヘッダ内にて以下の記述を行います。

<script type="text/javascript">
  document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">')
</script>

この記述は毎回記述することになるので、テンプレとして覚えておいて問題ありません。

GUIの記述

GUIの設定ではワークフロー実行時の動作を記述するわけではないので、このファイルに記述するものは設定項目を入力するためのフォームになります。

フォームに入力された値は、何らかの方法でワークフローの設定値としてAlteryx側に渡してやる必要があります。

参考 : AlteryxのワークフローをXMLファイルとして読む

フォームに入力された値とワークフローの設定とをやりとりする方法は以下の2種類があります。

通常のHTMLタグを利用し、JavaScriptでやりとりする
Alteryxの独自のタグを使い属性値として対応関係を記述

では、これらのやり方を順に見ていきましょう

通常のHTMLタグを利用する

通常のHTMLタグでワークフローの設定値とやりとりするには、特定のタイミングで呼び出される関数を実装する必要があります。 Alteryxでのワークフロー作成時には、

ツールが選択された時にそのツールの設定画面が表示される
ツールの選択が解除された際に他のツールやワークフローの設定画面に切り替わる

といった動きになっています。そのため、

ツールが選択された際に呼び出される関数で現在の設定値を取得してフォームに値を入れる
ツールの選択が解除された際に呼び出される関数でフォームに入力されている値を設定値に入れる

という動きを行う2つの関数を実装するのがもっとも基本的な設定となります。それぞれの関数としては、以下のものを実装します。

関数	呼び出されるタイミング
window.Alteryx.Gui.SetConfiguration	ツールが選択された時
window.Alteryx.Gui.GetConfiguration	ツールの選択が解除された時

例えば、それぞれに以下のような記述をすることでフォームとワークフローの設定値とのやりとりが行えます。

// SetConfigurationはツールが選択された際に呼び出される
// 選択されたタイミングですでに設定してある値を取得してフォームに入れる
window.Alteryx.Gui.SetConfiguration = function() {
  // 初回設定ではないことを確認する
  // 初回はまだ値が設定されていないので取得しようとするとエラーになる
  if (currentToolConfiguration && currentToolConfiguration.IsFirstConfig === false) {
      // ワークフローの設定で"a"という値で設定されたものを取得する
      var conf_data = currentToolConfiguration.Configuration.Configuration.conf
      // id属性で対象のタグを取得してその値に設定値を入れる
      document.getElementById("conf_data").value = conf
  }
}

// GetConfigurationはツールの選択が解除された際に呼び出される
// 選択解除されたタイミングでフォームの値をワークフローの設定値に入れる
window.Alteryx.Gui.GetConfiguration = function() {
    var conf_data = document.getElementById("conf_data").value
    // JSONを文字列化して設定値として渡す
    window.Alteryx.JsEvent(JSON.stringfy({
        Event: 'GetConfiguration',
        Configuration: {
            Configuration: {
                conf: conf_data
            }
        },
        Annotation : conf_data
    }))
}

HTMLの動作とライフサイクル関数

HTML GUIではJavaScriptを利用しています。上記の例では、Alteryxで利用するのに必要な設定でしたが通常のHTML同様、任意のJavaScriptやCSSをGUI上で利用することが可能です。もちろんこれらのJSやCSSは別ファイルに定義してHTMLから読み込むことも可能です。

この仕組みを利用すると、任意のタイミングで特定の要素の表示・非表示を切り替えるなどして画面遷移のような仕組みを作ることも可能です。実際、HTML GUIが使われているGoogle Sheets Inputでは、この仕組みを利用して認証方式の切り替えや、ファイル・シートの選択画面への遷移などを行なっています。

そうなってくると、例えばすでに認証を通している場合は最初からファイル選択画面にしたいなどの要望も出てくるかと思います。それを実現するために、AlteryxではSet/GetConfiguration以外にもいくつかの関数が用意されています。

ツールが選択された際に呼び出される関数とその順番

呼び出される順番	関数名	タイミング
1	SetConfiguration	ツールが選択された際
2	BeforeLoad	設定値の読み込みが完了する前
3	AfterLoad	設定値の読み込みが完了した際

ツールの選択が解除された際に呼び出される関数とその順番

呼び出される順番	関数名	タイミング
1	BeforeGetConfiguration	GetConfigurationが呼び出される前
2	GetConfiguration	ツールの選択が解除された際

これらを利用することで、

AfterLoadで認証がすでに完了していれば最初から画面遷移した状態にする
BeforeGetConfigurationで入力値に対する何らかの加工をする

などといったことも可能になります。

また、Alteryx上でツール下部に表示されるものを定義するための関数も用意されています。

関数名
Annotation

こちらはGetConfigurationの際にワークフローの設定に渡していたJSON中の"Annotation"と同じものになるので、どちらで指定しても問題ありません。この後、解説するAlteryx独自タグを利用する場合はライフサイクル関数を利用しなくてもよくなるので、その際はAnnotation関数を利用することになります。

Alteryx独自タグを記述する

ここまでの流れで、JavaScriptを利用してフォームの値と設定値を結びつける方法を見ていきました。しかし、JavaScriptでプログラムを書いて細かく指定しなくても単純にフォームと設定値のマッピングさえできればいいという場合も多いでしょう。そういった場合に便利なのがこの独自タグの記述です。

独自タグは以下のように2つの属性を指定して記述します。

<ayx data-ui-props="<フォームの要素に関する設定>" data-item-props="<ワークフローの設定値との対応関係>"></ayx>

それぞれ属性には設定項目と設定値をJSON形式で記述します。

data-ui-props

data-ui-propsでは、フォームの要素に関する設定を行います。どのような要素を配置するかにかかわらず共通のものと、要素の種類ごとに異なる設定項目があります。

共通の項目としては

項目	内容
type	フォームの種類。"TextBox"や"Button"などを指定する
widgetId	項目名

typeで指定した項目ごとに実際に表示されるものが異なります。例えば、"TextBox"を指定した場合は、1行のテキスト入力用のフォームとなります。

また、typeで指定した項目ごとにさらに設定項目があります。 TextBoxであれば、以下のようなものが設定可能です

項目	内容
password	trueにすることでパスワード入力用の非表示なものにする
placeholder	何も入力されていない時に表示される、グレーアウトされ他文字列

どのようなフォームの種類があって、それぞれどのような値を設定できるのかについては以下をご覧ください。

data-item-props

data-item-propsではワークフローの設定値との対応関係に関する設定を行います。こちらの設定項目は、以下の2つになります。

項目	内容
dataName	設定項目名
dataType	データの型(後述)

これらの要素を使った実際のTextBoxを配置するタグは以下のような感じになります。

<ayx
    data-ui-props="{type: 'TextBox', widgetId: 'A'}" 
    data-item-props="{dataName: 'A', dataType: 'SimpleString'}">
</ayx>

ayxタグの属性をJSで指定する

data-ui-props, data-item-propsは中身がJSONなので、どうしても煩雑な感じになってしまいます。それを回避するために、これらの要素をJSで記述して、ayxタグからはそれを参照させる方法もあります。やりかたとしては、適当なネームスペースを作成して、そこで値を定義して利用します。

<script>
  window.hogeNS = {}
  window.hogeNS.widgetAUI = {
    type: "TextBox",
    widgetId: "A"
  }
  window.hogeNS.widgetAItem = {
    dataName: "A",
    dataType: "SimpleString"
  }
</script>
...
...
<ayx data-ui-props="window.hogeNS.widgetAUI" data-item-props="window.hogeNS.widgetAItem"></ayx>